This sample demonstrates a variety of techniques and features of Carbon which alone may not have warranted their own sample.

Metrowerks CodeWarrior 8 was used to create the project to demonstrate how to use some of its packaging features.  To build this sample, first build GrabBag using ProjectBuilder to set up the entire package bundle, then (optionally) use Metrowerks to build the CFM Carbon binary.

This sample demonstrates:

New in this version:

 DataBrowser and colored text
The DataBrowser does not have built in support for colored text.  Drawing colored text requires implementing a DataBrowserCustomCallback.  The simple browser control implements colored text, cell selection, and support for movable columns. 

-------------------

 Implementing advisory locks with "lockfiles"
The underlying BSD layer on Mac OS X 10.0->10.1 does not implement "mandatory" locks on files.  This means that if one application opens a file for exclusive 	write access, it really doesn't have "exclusive" access, and another application 	can write over the file.   A common approach is for an application to create a "lockfile" next to the file being opened, and check if a "lockfile" exists before opening a file.

 Overlay windows and large cursors
Since drawing directly to the window manager port is not supported on Mac OS X you can create an invisible overlay window and draw to this window.  These routines create a small overlay window, which follows the cursor around to simulate a large cursor.
 
 Sheet Alerts
Contains routines for displaying a sheet alert on Mac OS X, which automatically display an Alert window when running under CarbonLib.

 How to bundle your CFM based application for use in CodeWarrior
CodeWarrior now has some built in support for bundles, but you may find that as you take advantage of Nib files, Help, localized resources, and other customizations it's best to create and edit those files directly within your target bundle.

 How to install the default event handlers without really using RunApplicationEventLoop()
 How to efficiently set up and use cooperative threads from a CarbonEvent based application
Calling RunApplicationEventLoop() installs a number of default toolbox CarbonEvent handlers for you, but at the same time is not very efficient for use with cooperative threads as noted in Technical Q&A 1061 <http://developer.apple.com/qa/qa2001/qa1061.html>.  The workaround implemented in the sample code installs a one-shot event loop timer to fire immediately and then calls RunApplicationEventLoop().  The timer fires immediately and from within the handler we effectively do the same thing as RunApplicationEventLoop() by calling ReceiveNextEvent() and SendEventToEventTarget() from within a loop.  The difference is that we also call YieldToAnyThread() to give time to our cooperative threads.

 Uses CarbonEvents on the Application, window, and control targets
Pure Carbon Event based application demonstrates how to subscribe to, and handle various events on different targets.

 Uses EventLoop Timers
Installs one-shot and reoccurring Event Loop Timers.

 How to use Nib's within your application
	- How to set up command IDs within InterfaceBuilder
	- How to automatically set up help tags for Mac OS X within InterfaceBuilder
Creating UI elements in InterfaceBuilder and installing default CarbonEvent Handlers allows you to rapidly get your UI up and running.  InterfaceBuilder also allows you to set command IDs to controls and menus.  Some command IDs are predefined in CarbonEvents.h, such as "kHICommandBringAllToFront" which have default handlers installed to do the right thing.  You may also define your own command IDs for easy parsing within your event handlers.

InterfaceBuilder also allows you to set up and attach Help Tags to UI elements.  To set attributes of controls and other UI elements you need to "Get Info" on the selected element.  This brings up the "Get Info" window which allows you to set attributes, command information, size, and help strings.  Currently, as of CarbonLib 1.5d1, the Help Tags do not display on Mac OS 9, but do display on Mac OS X.

Tab controls
Tab control switching is not done automatically within Carbon.  This demonstrates how to attach a CarbonEvent handler to a tab control and handle the tab pane switching from within the event handler.

How to enable the Preferences menu
Shows a very simple window when "Preferences" is chosen from the application menu.

 CFPreferences
CFPreferences allow for an abstraction between your application and the actual format and location of the preferences.  You simple save and retrieve preference information by tag names.

 How to add a help book
Help books within bundled applications are not automatically handled correctly on Mac OS 8/9.  On Mac OS 8/9 you'll have to add your own "<Your App> Help ?" menu item, and are also responsible for loading the help book.  This is actually easier since you don't have to create an AppleGuide file and link it to the creator of your application.

 How to add a custom menu item to the Help menu
This code was taken from Technical Q&A's 1022 and 1006, and demonstrates how to add an html help book to your bundle by adding the appropriate info.plist entries.  Also shows how to add additional items within the Help menu.

 128 Bit Icon
This sample adds an icns file referenced from its info.plist viewable when launched under Mac OS X.

 Calls Mach-O code from CFM application
The GetMachineNameAsCFString() routine gets the file sharing name of the machine regardless of OS version.  On Mac OS X (<10.1) it gets it from the SystemConfiguration/preferences.xml XML file by doing a dictionary lookup, and On Mac OS X (>=10.1) It calls the Mach-O routine CSCopyMachineNameProc() to retrieve the name.

